<?php
declare(strict_types=1);
namespace service\service;

use service\ext\PageData;
use service\vo\user\User;

/**
 * 用户接口
 */
interface UserService
{
    /**
     * 异常提示信息
     */
    const ERROR_USER_EXISTS = 'ERROR_USER_EXISTS';  //用户已存在
    const ERROR_USER_NOT_EXISTS = 'ERROR_USER_NOT_EXISTS';  //用户不存在
    const ERROR_USER_EMAIL_EXISTS = 'ERROR_USER_EMAIL_EXISTS';	//邮箱已存在
    const ERROR_USER_PHONE_EXISTS   =   'ERROR_USER_PHONE_EXISTS';  //手机号已存在
    const ERROR_USER_CAN_NOT_EXISTS = 'ERROR_USER_CAN_NOT_EXISTS';  //用户不能被删除
    const ERROR_USER_LOGIN_FAILED = 'ERROR_USER_LOGIN_FAILED';  //登录异常，用户名或密码错误
    const ERROR_USER_OLD_PWD_ERROR = 'ERROR_USER_OLD_PWD_ERROR'; //旧密码错误

    /**
     * 添加用户
     *
     * @param User $user 用户对象
     * @return int 新增的用户id
     *
     * @throws
     *  ERROR_USER_EXISTS
     *  ERROR_USER_EMAIL_EXISTS
     *  ERROR_USER_PHONE_EXISTS
     */
    public function addUser(User $user): int;

    /**
     * 编辑用户
     * @param User $user    用户对象
     * @return int  返回影响的行数
     *
     * @throws
     *  ERROR_USER_EMAIL_EXISTS
     *  ERROR_USER_PHONE_EXISTS
     */
    public function editUser(User $user): int;

    /**
     * 删除用户
     * @param int $userId   用户id
     * @return int
     *
     * @throws
     *  ERROR_USER_CAN_NOT_EXISTS
     *
     * @see 1.当用户有创建的题目，不可被删除
     *      2.删除用户时将用户的连带数据一起删除
     *          其中包括：用户练习配置，练习题目表，用户收藏表，用户练习题目统计表，vip订单表
     */
    public function deleteUser(int $userId): int;

    /**
     * 删除多个用户
     * @param array $userIds  用户id集合
     * @return int  返回影响的行数
     *
     * @throws
     *      ERROR_USER_CAN_NOT_EXISTS
     *
     * @see 1.当其中任何一个用户有创建的题目时，所有用户均不可删除
     *      2.删除用户时将用户的连带数据一起删除
     *          其中包括：用户练习配置，练习题目表，用户收藏表，用户练习题目统计表，vip订单表
     */
    public function deleteUsers(array $userIds): int;

    /**
     * 用户修改密码
     * @param int $userId   用户id
     * @param string $newPassword   新密码
     * @param string $oldPassword   旧密码
     * @param bool $isCheckOldPassword  是否检查旧密码是否正确
     * @return int  返回影响的行数
     *
     * @throws
     *      ERROR_USER_OLD_PWD_ERROR
     */
    public function changeUserPassword(int $userId, string $newPassword, string $oldPassword, bool $isCheckOldPassword): int;

    /**
     * 用户登录
     * @param string $account  登录的账号，可以是用户名/邮箱/手机号
     * @param string $password  密码
     * @return User 用户对象
     *
     * @throws
     *      ERROR_USER_LOGIN_FAILED
     */
    public function login(string $account, string $password): User;

    /**
     * 增加用户的积分
     * @param int $userId   用户id
     * @param int $integral 增加的积分值
     * @return int 影响的行数
     */
    public function incUserIntegral(int $userId, int $integral): int;

    /**
     * 减少用户的积分
     * @param int $userId   用户id
     * @param int $integral 积分值
     * @return int  影响的行数
     */
    public function decUserIntegral(int $userId, int $integral) : int;

    /**
     * 设置用户的vip过期日期
     * @param int $userId   用户id
     * @param string $vipExpireTime 过期日期
     * @return int  影响的行数
     */
    public function setUserVipExpireTime(int $userId, string $vipExpireTime): int;

    /**
     * 获取用户信息
     * @param int $userId   用户id
     * @return User 用户对象
     *
     * @throws
     *  ERROR_USER_NOT_EXISTS
     */
    public function getUserById(int $userId): User;

    /**
     * 获取多个用户信息
     * @param array $userIds    用户id集合
     * @return array 用户对象集合
     */
    public function getUserByIds(array $userIds): array;

    /**
     * 根据用户名判断用户是否存在
     * @param string $username  用户名
     * @return bool 存在返回true，不存在返回false
     */
    public function checkUserExistsByUsername(string $username): bool;

    /**
     * 根据email判断用户是否存在
     * @param string $email 邮箱
     * @return bool 存在返回true，不存在返回false
     */
    public function checkUserExistsByEmail(string $email): bool;

    /**
     * 根据手机号判断用户是否存在
     * @param string $phone 手机号
     * @return bool 存在返回true，不存在返回false
     */
    public function checkUserExistsByPhone(string $phone): bool;

    /**
     * 搜索用户
     * @param int $currentPage 当前页
     * @param int $pageSize 每页显示数量
     * @param array $filterCriteria //搜索条件数组，其中的value是搜索值，其中的key从下面字符串中取
     *        'Name'            =>    用户名，模糊查询
     *        'Email'            =>    邮箱，模糊查询
     *        'Phone'            =>    手机号，模糊查询
     *        'Status'        =>    状态
     *        'AddTime'        =>    时间，array('start'=>'开始时间','end'=>'结束时间')
     * @param array $sorterCriteria //排序条件，其中的value是搜索值，其中的key从下面字符串中取
     *        'ID'    =>    true为升序false为降序
     *
     * @return PageData
     */
    public function searchUser(int $currentPage, int $pageSize, array $filterCriteria, array $sorterCriteria): PageData;
}